Skip to content

Conversation

sd109
Copy link
Member

@sd109 sd109 commented Jun 16, 2023

It looks like integrating aide with our existing code to generate a proper OpenAPI schema is going to be a little difficult (more trait bound issues which I think stem from our custom models::Response implementation). I will continue looking into this but in the mean time, this PR adds two endpoints which return simple JSON schema to at least provide some form of live documentation.

@sd109
Copy link
Member Author

sd109 commented Jun 16, 2023

Generated request schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "RequestData",
  "description": "Request data for operations",
  "type": "object",
  "required": [
    "bucket",
    "dtype",
    "object",
    "source"
  ],
  "properties": {
    "bucket": {
      "description": "S3 bucket containing the object",
      "type": "string",
      "minLength": 1
    },
    "dtype": {
      "description": "Data type",
      "allOf": [
        {
          "$ref": "#/definitions/DType"
        }
      ]
    },
    "object": {
      "description": "S3 object containing the data",
      "type": "string",
      "minLength": 1
    },
    "offset": {
      "description": "Offset in bytes of the numerical data within the object",
      "type": [
        "integer",
        "null"
      ],
      "format": "uint",
      "minimum": 0.0
    },
    "order": {
      "description": "Order of the multi-dimensional array",
      "anyOf": [
        {
          "$ref": "#/definitions/Order"
        },
        {
          "type": "null"
        }
      ]
    },
    "selection": {
      "description": "Subset of the data to operate on",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/definitions/Slice"
      },
      "minItems": 1
    },
    "shape": {
      "description": "Shape of the multi-dimensional array",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "integer",
        "format": "uint",
        "minimum": 0.0
      },
      "minItems": 1
    },
    "size": {
      "description": "Size in bytes of the numerical data from the offset",
      "type": [
        "integer",
        "null"
      ],
      "format": "uint",
      "minimum": 1.0
    },
    "source": {
      "description": "URL of the S3-compatible object store",
      "type": "string",
      "format": "uri"
    }
  },
  "additionalProperties": false,
  "definitions": {
    "DType": {
      "description": "Supported numerical data types",
      "oneOf": [
        {
          "description": "[i32]",
          "type": "string",
          "enum": [
            "int32"
          ]
        },
        {
          "description": "[i64]",
          "type": "string",
          "enum": [
            "int64"
          ]
        },
        {
          "description": "[u64]",
          "type": "string",
          "enum": [
            "uint32"
          ]
        },
        {
          "description": "[u64]",
          "type": "string",
          "enum": [
            "uint64"
          ]
        },
        {
          "description": "[f64]",
          "type": "string",
          "enum": [
            "float32"
          ]
        },
        {
          "description": "[f64]",
          "type": "string",
          "enum": [
            "float64"
          ]
        }
      ]
    },
    "Order": {
      "description": "Array ordering\n\nDefines an ordering for multi-dimensional arrays.",
      "oneOf": [
        {
          "description": "Row-major (C) ordering",
          "type": "string",
          "enum": [
            "C"
          ]
        },
        {
          "description": "Column-major (Fortran) ordering",
          "type": "string",
          "enum": [
            "F"
          ]
        }
      ]
    },
    "Slice": {
      "description": "A slice of a single dimension of an array\n\nThe API uses NumPy slice (i.e. [start, end, stride]) semantics where:\n\nWhen start or end is negative: * positive_start = start + length * positive_end = end + length Start and end are clamped: * positive_start = min(positive_start, 0) * positive_end + max(positive_end, length) When the stride is positive: * positive_start <= i < positive_end When the stride is negative: * positive_end <= i < positive_start",
      "type": "object",
      "required": [
        "end",
        "start",
        "stride"
      ],
      "properties": {
        "end": {
          "description": "End of the slice",
          "type": "integer",
          "format": "int"
        },
        "start": {
          "description": "Start of the slice",
          "type": "integer",
          "format": "int"
        },
        "stride": {
          "description": "Stride size",
          "type": "integer",
          "format": "int"
        }
      },
      "additionalProperties": false
    }
  }
}

Generated response schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Response",
  "description": "Response containing the result of a computation and associated metadata.",
  "type": "object",
  "required": [
    "body",
    "dtype",
    "shape"
  ],
  "properties": {
    "body": {
      "description": "Raw response data as bytes. May represent a scalar or multi-dimensional array.",
      "type": "array",
      "items": {
        "type": "integer",
        "format": "uint8",
        "minimum": 0.0
      }
    },
    "dtype": {
      "description": "Data type of the response",
      "allOf": [
        {
          "$ref": "#/definitions/DType"
        }
      ]
    },
    "shape": {
      "description": "Shape of the response",
      "type": "array",
      "items": {
        "type": "integer",
        "format": "uint",
        "minimum": 0.0
      }
    }
  },
  "definitions": {
    "DType": {
      "description": "Supported numerical data types",
      "oneOf": [
        {
          "description": "[i32]",
          "type": "string",
          "enum": [
            "int32"
          ]
        },
        {
          "description": "[i64]",
          "type": "string",
          "enum": [
            "int64"
          ]
        },
        {
          "description": "[u64]",
          "type": "string",
          "enum": [
            "uint32"
          ]
        },
        {
          "description": "[u64]",
          "type": "string",
          "enum": [
            "uint64"
          ]
        },
        {
          "description": "[f64]",
          "type": "string",
          "enum": [
            "float32"
          ]
        },
        {
          "description": "[f64]",
          "type": "string",
          "enum": [
            "float64"
          ]
        }
      ]
    }
  }
}

@sd109 sd109 requested a review from markgoddard June 16, 2023 11:29
Copy link

@markgoddard markgoddard left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like a reasonable compromise.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants